BCI NET 2/BCI NET 2.iso/archives/programming/gui/bgui11b.lha/docs/windowclass.doc

Text File | 1994-11-21 | 27.4 KB | 775 lines

           $RCSfile: windowclass.doc,v $
        Description: Windowclass documentation.
          Copyright: (C) Copyright 1994 Jaba Development.
                     (C) Copyright 1994 Jan van den Baard.
                     All Rights Reserved.

            $Author: jaba $
          $Revision: 1.8 $
              $Date: 1994/11/15 14:27:16 $
------------------------------------------------------------------------------

TABLE OF CONTENTS

windowclass/--background--
windowclass/Methods
windowclass/Attributes

windowclass/--background--                          windowclass/--background--

    NAME
        Class:          windowclass
        Superclass:     ROOTCLASS
        Include File:   <libraries/bgui.h>

    FUNCTION
        To  provide  an  easy  to use BGUI interface to intuition windows. The
        window  class  provides just about anything you need to create windows
        with a fully font sensitive and size adjustable GUI.

windowclass/Methods                                        windowclass/Methods

    NEW METHODS
        WM_OPEN -- This method must be used to open the window.  When a window
                object is created it does not open right away.

                Returns a pointer to the opened window uppon success  and NULL
                uppon failure.

        WM_CLOSE -- This method must be used to close the window again.  It is
                safe to call this method even when the window is not open.

                Returns TRUE uppon success and FALSE uppon failure.

        WM_SLEEP -- With this method you can put your window to sleep  when it
                is  open.   This  is  done  by  setting  up a  small invisible
                requester and a busy pointer.

                Returns TRUE uppon success and FALSE uppon failure.

        WM_WAKEUP -- This methos must be  used to  wake  up the  window again.
                Please note that you must wake up the window as many  times as
                you have put it to sleep before you can actually use it again.
                Both the WM_SLEEP and WM_WAKEUP methods can be nested.

                Returns TRUE uppon success and FALSE uppon failure.

        WM_HANDLEIDCMP -- This method must be  used  to call  the  windowclass
                event handler. The event handler will  act  uppon the messages
                present at the window it's message  port  and  return  you one
                of the following return codes:

                WMHI_CLOSEWINDOW -- The window it's close gadget was selected.
                WMHI_NOMORE -- No more messages waiting.
                WMHI_INACTIVE -- The window was de-activated.
                WMHI_ACTIVE -- The window was activated.
                WMHI_IGNORE -- Ignore this result.

                Any return code which differs from the ones  above is  the  ID
                of a selected object (gadget or menu).

                Please look at the demo programs for more information.

        WM_GADGETKEY -- With this method you  can  assign a  key to  trigger a
                gadget object in the window.  This method  uses the  following
                custom message structure:

                struct wmGadgetKey {
                        ULONG             MethodID;  /* WM_GADGETKEY */
                        struct Requester *wmgk_Requester;
                        Object           *wmgk_Object;
                        STRPTR            wmgk_Key;
                };

                wmgk_Requester -- This version of the library does not support
                        BGUI gadget objects in requesters  so this  field must
                        be set to NULL.

                wmgk_Object -- This must be  a  pointer to  the  object  which
                        must be controlled by the key.

                wmgk_Key -- This must point to a  string  in   which  a single
                        character is located. The character is  the  key which
                        controls the object when it is pressed.

                Returns TRUE uppon success and FALSE uppon failure.

        WM_KEYACTIVE, WM_KEYINPUT, WM_KEY_INACTIVE -- These three  methods are
                sent to the gadget object during a key-session.  Please  refer
                to the "methods.doc" file for more information.

        WM_DISABLEMENU, WM_CHECKITEM -- These  two  methods  must  be  used to
                disable or enable a menu or a menu item or to set or clear the
                check mark of a CHECKIT item.   These  methods  both  use  the
                following custom message structure:

                struct wmMenuAction {
                        ULONG             MethodID; /* Any of the above. */
                        ULONG             wmma_MenuID;
                        ULONG             wmma_Set;
                };

                wmma_MenuID -- This must be the ID of the  menu/item  on which
                        the operation is done. The ID is  the value  which you
                        set in the nm_UserData field of the NewMenu structure.

                wmma_Set -- This is a boolean which  disables/checks  the menu
                        when set to  TRUE  or  enables/unchecks the  menu when
                        set to FALSE.

                Returns TRUE uppon success and FALSE uppon failure.

        WM_MENUDISABLED, WM_ITEMCHECKED -- These two methods  must  be used to
                query about the disabled/checked state of a menu. Both methods
                use the following custom message structure:

                struct wmMenuQuery {
                        ULONG             MethodID; /* Any of the above. */
                        ULONG             wmmq_MenuID;
                };

                wmmq_MenuID -- This must be the ID of the  menu/item  on which
                        the operation is done. The ID is  the value  which you
                        set in the nm_UserData field of the NewMenu structure.

                Returns TRUE if the menu is disabled/checked and FALSE if not.
                A return code of ~0 means that the menu is unknown or no menus
                are available.

        WM_TABCYCLE_ORDER -- With this method you can  determine the  order of
                tab-cycling.  This method uses  the  following  custom message
                structure:

                struct wmTabCycleOrder {
                        ULONG             MethodID; /* WM_TABCYCLE_ORDER */
                        Object           *wtco_Object1;
                        /* Object        *wtco_Object2; */
                        /* ... */
                        /* NULL */
                };

                wtco_Object1 -- The first of a the objects which  will be  set
                        in the tab-cycle chain.   Please  note  that you  must
                        terminate the method with a NULL pointer.

                Returns TRUE uppon success and FALSE uppon failure.

        WM_GETAPPMSG -- This method must be used  to get the AppWindow message
                when one is available.  Please note that _you_ are  resposible
                for replying the message.

                Returns a pointer to the AppMessage or NULL when  there was no
                message.

        WM_ADDUPDATE -- This method must be used  to  perform  simple map-list
                notification with  externalclass  objects.  The  externalclass
                objects are not able to perform  notification  like  the other
                gadget classes. This method uses the  following custom message
                structure:

                struct wmAddUpdate {
                        ULONG             MethodID; /* WM_ADDUPDATE */
                        ULONG             wmau_SourceID;
                        Object           *wmau_Target;
                        struct TagItem   *wmau_MapList;
                };

                wmau_SourceID -- This must be the ID of the object that send's
                        the notification message.

                wmau_Target -- This must be a  pointer  to  the  object  which
                        must be updated by the notiication.

                wmau_MapList -- This can pointe to  an  array  of  tags  which
                        contain the attributes to map.  This may also  be NULL
                        in which case no mapping is done.

                Return TRUE uppon success and FALSE uppon failure.

        WM_REPORT_ID ** V38 ** -- This method  will  allow  an  IDCMP-hook  or
                Verify-hook to report ID's  to  the  application program.   It
                will  stack  the  ID(s)  to  report  and  pass  them  to   the
                application the next time the WM_HANDLEIDCMP method is called.
                This  method  uses the following custom message structure:

                struct wmReportID {
                        ULONG           MethodID;       /* WM_REPORT_ID     */
                        ULONG           wmri_ID;
                        ULONG           wmri_Flags;
                };

                wmri_ID -- This is the ID that is put on the stack.  Next time
                        the application  call's  WM_HANDLEIDCMP on  the object
                        the ID's on the stack are returned.

                wmri_Flags -- This may contain any of the following flags:

                        WMRIF_DOUBLE_CLICK -- When this flag is set  the ID to
                                report   is  put  on  the  stack  twice  which
                                effectivly simulates a double-click.

                Returns TRUE uppon success and FALSE uppon failure.

    CHANGED METHODS
        OM_DISPOSE -- When  this  method is called all objects attached to the
                window with the WINDOW_MasterGroup attribute are also disposed
                of.

windowclass/Attributes                                  windowclass/Attributes

    NAME
        WINDOW_Position -- ( ULONG )

    FUNCTION
        To determine the position at which the window is opened. These are the
        possibilities:

        POS_CENTERSCREEN -- The window is centered in the visible part  of the
                screen it is opened on.
        POS_CENTERMOUSE -- The window is centered under  the mouse.  Depending
                on the location of the mouse this might differ a little.
        POS_TOPLEFT -- The window is opened  at  the  top-left  corner  in the
                visible part of the screen it is opened on.

        Default is POS_CENTERSCREEN. Applicability is (I).

    SEE ALSO
        WINDOW_PosRelBox

    NAME
        WINDOW_ScaleWidth, WINDOW_ScaleHeight -- ( ULONG )

    FUNCTION
        To open a window larger than it's minimum size. The data you pass with
        these tags must be the percentage (0%..100%) of the  visible  size  of
        the screen minus the minimum size of the window.  For example you have
        a  window which is 100 pixels wide at it's minimum size  on  a  screen
        which   is  1000   pixels   wide   (visible)   and   you  pass  25  as
        WINDOW_ScaleWidth  the window is opened 325 pixels wide.

        (( 1000 - 100 ) / 100 ) * 25 = 225

        225 + 100 = 325

        Defaults are 0. Applicability is (I).

    NAME
        WINDOW_LockWidth, WINDOW_LockHeight -- ( BOOL )

    FUNCTION
        To disable sizing the width or height of a window.

        Defaults are FALSE. Applicability is (I).

    NAME
        WINDOW_PosRelBox -- ( struct IBox * )

    FUNCTION
        To open the window centered in the described box.  The  data  you pass
        here must be a pointer to a struct IBox in which the location and size
        of the box is described. This will allow you to easely center a window
        uppon another window like this:

        struct Window           *parent;
        struct IBox              position;
        Object                  *window_object;

        /*
        **      Copy the parent location/size.
        **/
        position = *(( struct IBox * )&parent->LeftEdge );

        window_object = WindowObject,
                WINDOW_PosRelBox,               &position,
                ....
        EndObject;

    SEE ALSO
        WINDOW_Position

    NAME
        WINDOW_DragBar,         WINDOW_SizeGadget,         WINDOW_CloseGadget,
        WINDOW_DepthGadget -- ( BOOL )

    FUNCTION
        To switch on or off the corresponding system gadgets.

        Default for all are TRUE. Applicability is (I).

    NAME
        WINDOW_SizeBottom, WINDOW_SizeBright -- ( BOOL )

    FUNCTION
        To determine the place of the sizing gadget.

        Default is TRUE for bottom and FALSE for right. Applicability is (I).

    NAME
        WINDOW_Activate -- ( BOOL )

    FUNCTION
        To activate the window right after it is opened.

        Default is TRUE. Applicability is (I).

    NAME
        WINDOW_RMBTrap -- ( BOOL )

    FUNCTION
        To set/clear the WFLG_RMBTRAP  flag.  When set this disables the right
        from  activating  the  menu-strip.   It will also make the right mouse
        button visible in intuition events.

        Default is FALSE. Applicability is (I).

    NAME
        WINDOW_SmartRefresh -- ( BOOL )

    FUNCTION
        To set/clear the WFLG_SMART_REFRESH flag.

        Default is FALSE. Applicability is (I).

    NAME
        WINDOW_ReportMouse -- ( BOOL )

    FUNCTION
        To set/clear the WFLG_REPORTMOUSE flags.

        Default is FALSE. Applicability is (I).

    NAME
        WINDOW_IDCMP -- ( ULONG )

    FUNCTION
        To set extra IDCMP flags which are not automatically set by the window
        class  itself.  This  might  be  necessary  for  the  WINDOW_IDCMPHook
        described below.   The following  flags are  automatically set  by the
        window class:

        IDCMP_RAWKEY                    - Key control of gadgets.
        IDCMP_GADGETUP                  - The obvious.
        IDCMP_CHANGEWINDOW              - To track window changes.
        IDCMP_INACTIVEWINDOW            - To report window inactivation.
        IDCMP_ACTIVEWINDOW              - To report window activation.
        IDCMP_IDCMPUPDATE               - For WM_ADDUPDATE notification,
                                          tab-cycling and continues slider and
                                          scroller reporting.
        IDCMP_CLOSEWINDOW               - To report clicking the close gadget.
        IDCMP_MENUPICK                  - To report menu-selections.

        Please  note  that  IDCMP_VANILLAKEY  must  _not_  be set. The current
        keyboard handling does not allow this.

        Default is 0. Applicability is (I).

    SEE ALSO
        WINDOW_IDCMPHook

    NAME
        WINDOW_SharedPort -- ( struct MsgPort * )

    FUNCTION
        To use a shared message port for the window.  If you pass a pointer to
        a valid message port here the window will use this  port for receiving
        events.

        Default is NULL. Applicability is (I).

    NAME
        WINDOW_Title, WINDOW_ScreenTitle -- ( STRPTR )

    FUNCTION
        To set the window title and the title of  the screen  while the window
        is active.

        Defaults are NULL. Applicability is (ISU).

    NAME
        WINDOW_MenuStrip -- ( struct NewMenu * ) ( struct Menu * )

    FUNCTION
        This attribute has two data types to be considered.  Uppon creation of
        the  window  object  the  data  expected  is  a pointer to an array of
        NewMenu  structures  as  defined  in  <libraries/gadtools.h>. When you
        obtain  this  attribute  with  OM_GET  you  will  get a pointer to the
        created menus.

        To  make  the  menus  visible  to  your  program  you  must give every
        selectable  menu an ID. The ID must be placed in the nm_UserData field
        of the corresponding NewMenu structure.

        Example:

        #define ID_ABOUT        1
        #define ID_QUIT         2

        struct NewMenu Menus {
                { NM_TITLE,  "Project",   NULL, 0, 0, NULL },
                { NM_ITEM,   "About...",  "?",  0, 0, (APTR)ID_ABOUT },
                { NM_ITEM,   NM_BARLABEL, NULL, 0, 0, NULL },
                { NM_ITEM,   "Quit",      "Q",  0, 0, (APTR)ID_QUIT },
                { NM_END,    NULL,        NULL, 0, 0, NULL }
        }

        The  WM_HANDLEIDCMP  method  will  return ID_ABOUT when the "About..."
        item is selected and ID_QUIT when the "Quit" item is selected.

        Default is NULL. Applicability is (IG).

    NAME
        WINDOW_MasterGroup -- ( Object * )

    FUNCTION
        To  set  the master group containing all objects for the window.  This
        attribute   data   _must_  point  to a valid groupclass object or else
        the  window  object  creation    will    fail.   It's   currently  not
        possible   to   create   a  windowclass  object without a group object
        attached  to it. The data expected here is a pointer to the groupclass
        object  containing  all other gadget objects.

        Example:

        Object                  *WO_Window;

        WO_Window = WindowObject,
                WINDOW_Title,           "Whatever",
                ...
                WINDOW_MasterGroup,
                        HGroupObject, HOffset( 4 ), VOffset( 4 ),
                                StartMember,
                                        Button( "Quit", 0 ),
                                EndMember,
                        EndObject,
        EndObject;

        Default is NULL. Applicability is (I).

    NAME
        WINDOW_Screen -- ( struct Screen * )

    FUNCTION
        To set the custom screen on which the window should open.  If you want
        your  window  to  open on a custom screen you can pass a pointer to it
        here.  Please  note  that you  can use OM_SET to change this attribute
        only when the window is not open.

        Default is NULL (default public screen). Applicability is (IS).

    SEE ALSO
        WINDOW_PubScreenName

    NAME
        WINDOW_PubScreenName -- ( STRPTR )

    FUNCTION
        To set the name of the public screen on which the window should  open.
        Please note that you can use  OM_SET  to change  this  attribute  only
        when the window is not open.

        Default is NULL (default public screen). Applicability is (IS).

    SEE ALSO
        WINDOW_Screen

    NAME
        WINDOW_UserPort -- ( struct MsgPort * )

    FUNCTION
        To obtain a pointer to the message port of the window.

        Applicability is (G).

    NAME
        WINDOW_SigMask -- ( ULONG )

    FUNCTION
        To  obtain  the  window signal mask.

        Example:

        Object         *WO_Win;
        ULONG           mask;

        GetAttr( WINDOW_SigMask, WO_Win, &mask );

        do {
                Wait( mask );
                ...
        } while ( ... );

        Applicability is (G).

    SEE ALSO
        WINDOW_AppMask

    NAME
        WINDOW_IDCMPHook, WINDOW_VerifyHook -- ( struct Hook * )

    FUNCTION
        To  tie  yourself  into  the IDCMP handling of the window.  With these
        attributes  you  can  set a hook which is called uppon  events set  by
        the  WINDOW_IDCMPHookBits and/or WINDOW_VerifyHookBits attributes. The
        hooks are called as follows:

        void hookRoutine( hook, object, imsg )
                          A0    A2      A1

        struct Hook             *hook;
        Object                  *object;
        struct IntuiMessage     *imsg;

        The  pointer  to  the  IntuiMessage  structure  is read-only. Also the
        message  is  passed to you before it is reply'd so you should not take
        to long before returning.

        The  IDCMPHook  is  called  after  the window object has done it's own
        processing on the message. The VerifyHook is called directly while the
        window object does not need to process any verification messages.

        Default is NULL. Applicability is (I).

    SEE ALSO
        WINDOW_IDCMP, WINDOW_IDCMPHookBits, WINDOW_VerifyHookBits

    NAME
        WINDOW_IDCMPHookBits, WINDOW_VerifyHookBits -- ( ULONG )

    FUNCTION
        To  set  the  bits  that  will cause the IDCMPHook or VerifyHook to be
        called.  The bits you pass here are the standard system IDCMP_xxx flag
        bits  found in <intuition/intuition.h>. Please note that some of these
        bits  require  you  to set them first using the WINDOW_IDCMP attribute
        described above.

        Example:

        struct Hook             *idcmp_hook;
        Object                  *wd_obj;

        wd_obj = WindowObject,
                WINDOW_IDCMP,           IDCMP_INTUITICKS,
                WINDOW_IDCMPHook,       idcmp_hook,
                WINDOW_IDCMPHookBits,   IDCMP_INTUITICKS,
                ...
        EndObject;

        This   will   cause   the   WINDOW_IDCMPHook  to  be  called  at  each
        IDCMP_INTUITICKS event.

        Please note that the window class does not filter  out  any non-verify
        bits  from  the WINDOW_VerifyHookBits you pass. This means that if you
        set  IDCMP_GADGETUP  in  the  verification bits you will block out the
        window  object  event  handler  from  receiving  gadget  messages. The
        verification bits set should be restricted to the following bits:

        IDCMP_REQVERIFY
        IDCMP_MENUVERIFY

        Defaults are 0. Applicability is (I).

    SEE ALSO
        WINDOW_IDCMP, WINDOW_IDCMPHook, WINDOW_VerifyHook

    NAME
        WINDOW_Font -- ( struct TextAttr * )

    FUNCTION
        To  set the font to be used by the gadget objects. By default the font
        of  the  screen the window is opened on is used. With this tag you can
        select your own font.  Note that the font is opened with OpenFont() so
        please make sure it is present in memory.

        Default is NULL. Applicability is (I).

    SEE ALSO
        WINDOW_FallBackFont

    NAME
        WINDOW_FallBackFont -- ( struct TextAttr * )

    FUNCTION
        To  set the font to try whenever a window fails to open because it has
        grown  to big for the screen. By default the fallback font is topaz 8.
        If  you  pass a TextAttr here the window object will first try to fall
        back  to  the supplied font and, if that also fails, it will try topaz
        8. When topaz 8 fails the window will not open.  Note that the font is
        opened with OpenFont() so please make sure it is present in memory.

        Default is NULL. Applicability is (I).

    SEE ALSO
        WINDOW_Font

    NAME
        WINDOW_HelpFile -- ( STRPTR )

    FUNCTION
        Set the name of the file to be displayed when a  help-request  for the
        object arives. Please note that the full path-name must be given.

        Default is NULL. Applicability is (IS).

    SEE ALSO
        WINDOW_HelpNode, WINDOW_HelpLine

    NAME
        WINDOW_HelpNode -- ( STRPTR )

    FUNCTION
        Set the name of the node which is diplayed in the help window.

        Default is NULL. Applicability is (IS).

    SEE ALSO
        WINDOW_HelpFile, WINDOW_HelpLine

    NAME
        WINDOW_HelpLine - ( ULONG )

    FUNCTION
        Set the line number  from  which the  file is  displayed.  This may be
        useful if the help-file is not an AmigaGuide file.

        Default is 0. Applicability is (IS).

    SEE ALSO
        WINDOW_HelpFile, WINDOW_HelpNode

    NAME
        WINDOW_AppWindow -- ( BOOL )

    FUNCTION
        To make the window an AppWindow.

        Default is FALSE. Applicability is (I).

    SEE ALSO
        WINDOW_AppMask

    NAME
        WINDOW_AppMask -- ( ULONG )

    FUNCTION
        To  obtain  the app-window signal mask.

        Example:

        Object         *WO_Win;
        ULONG           mask;

        GetAttr( WINDOW_AppMask, WO_Win, &mask );

        do {
                Wait( mask );
                ...
        } while ( ... );

        Applicability is (G).

    SEE ALSO
        WINDOW_SigMask

    NAME
        WINDOW_UniqueID -- ( ULONG )

    FUNCTION
        To provide the window with an ID. The ID must be a 32bit integer which
        is  used  to  store  information on the window it's position and size.
        This  allows  you to close and dispose of the window object, re-create
        it  with the same ID, and the position and size of the window the last
        time it was open is still the same.

        This tag  tracks  the  complete window bounds but if you re-create and
        open your window with the WINDOW_PosRelBox tag specified only the size
        of the  window is re-stored. The size will remain the same as the last
        time the  window  was  open  but  the position will be adjusted to the
        bounds specified with the WINDOW_PosRelBox tag.

        The ID must be non-NULL.

        Default is 0 (no storage is done). Applicability is (I).

    SEE ALSO
        WINDOW_PosRelBox

    NAME
        WINDOW_Window -- ( struct Window * )

    FUNCTION
        To get a pointer to the window structure.  The pointer you get will be
        NULL if the window is not opened.

        Applicability is (G).

    NAME
        WINDOW_Bounds -- ( struct IBox * )

    FUNCTION
        To  enable  you  to pick the position and the size of the window. This
        attribute expects a pointer to a struct IBox in which the position and
        size are stored. The windowclass will check the values and adjust them
        if necessary. I.E. You cannot specify a size smaller than  the minimum
        possible size.  Query this attribute with  OM_GET to find  out exactly
        where the window is located and what it's size is.

        Querying this attribute with OM_GET is only  possible when  the window
        is open. To get this attribute with OM_GET you specify  a pointer to a
        struct IBox in the method.   The  class  will  write the bounds in the
        struct IBox.

        Please  note  that  this   attribute   overides  the  WINDOW_Position,
        WINDOW_ScaleWidth, WINDOW_ScaleHeight and WINDOW_PosRelBox attributes.

        Default is NULL. Applicability is (ISG).

    SEE ALSO
        WINDOW_Position, WINDOW_ScaleWidth, WINDOW_ScaleHeight,
        WINDOW_PosRelBox

    NAME
        WINDOW_HelpText -- ( STRPTR)

    FUNCTION
        To setup  a  text  which  will be displayed if the help-key is pressed
        while the  mouse  pointer  is located above the window. This attribute
        should be  used  to  attach small on-line help to the window. The text
        you specify will be shown in a small BGUI_RequestA() type of requester
        so you  must  make  sure  that  everything  fit's  nicely on a 600x200
        screen.

        The specified text may contain any of the infoclass command sequences.

        This   attribute  overides  the  WINDOW_HelpFile,  WINDOW_HelpNode and
        WINDOW_HelpLine attributes.

        Default is NULL. Applicability (IS).

    SEE ALSO
        WINDOW_HelpFile, WINDOW_HelpNode, WINDOW_HelpLine,
        infoclass/INFO_TextFormat, bgui.library/BGUI_RequestA()

    NAME
        WINDOW_NoBufferRP -- ( BOOL )

    FUNCTION
        When this attribute is  set to  TRUE the  windowclass  will  tell  the
        layout engine not to  setup a  buffer  RastPort  which  means that all
        rendering occures  on-screen.   This may be handy when you use objects
        which  take  some  time  to  render  like the colorwheel.gadget on 256
        colour screens.

        Default is FALSE. Applicability is (I).

    NAME
        WINDOW_AutoAspect -- ( BOOL )

    FUNCTION
        When this attribute is set the  windowclass  will  automatically  make
        aspect ratio dependant decisions  about the  resulting GUI.  Currently
        the only thing it does is selecting the frame  thickness.  Other stuff
        like spacing and offsets might be added in the future.

        Default is FALSE. Applicability is (I).